<html>
<head>
    <title>Simple XML Pipeline</title>
</head>
<body>
    <center>
        <h2>Simple XML Pipeline</h2>
        <a href="#overview">Overview</a> |
        <a href="#usage">Usage</a> |
        <a href="#status">Status</a> |
        <a href="pipeline-0.3.zip">Download (under a meg)</a> | 
        <a href="api/index.html">JavaDocs</a> |
        <a href="mailto:mrdon@twdata.org">Feedback</a>
    </center>
    <a name="overview" />
    <h3>Overview</h3>
        <p>
        The Simple XML Pipeline is primarily intended to make complex, multi-stage XML transformations easy by allowing the developer to create stages that specialize in particular operations and independently chain them together into pipelines.   The pipeline framework uses <a href="http://sax.sourceforge.net/">SAX</a>, a stream-based XML parsing technology, to maximize speed and memory efficiency.  The technology is based off of concepts and code developed by <a href="http://cocoon.apache.org">Apache Cocoon</a> rewritten to minimize external dependencies with the goal of making the pipeline framework easy to embed and develop with.
        </p>
        <p>
        As more and more applications rely on XML for information exchange, it becomes increasingly important to be able to easily process complex documents and transform from one schema to another.  For example, document-style SOAP messages are used to expose application functionality and integrate with other enterprise applications.  Unfortunately, not everyone agrees on what XML schema to use and other times, only a fraction of the information is needed.  This pipeline framework could be used to efficiently process the XML from one schema to another or even extract or insert key information between transformations.
        </p>
        <p>
        Why not just use Java's API for XSLT processing directly?  First, the XSLT transformer component of the pipeline supports compiled XSLTs stored in an Last Recently Used (LRU) cache.  Compiled stylesheets can increase processing performance by sometimes 3x to 4x.  Second, the pipeline allows you to easily insert addition stages to optimize processing.  For example, if the source XML document is rather large, introduce an element filtering stage before the XSLT stage to filter out unnecessary elements improving XSLT performance and memory usage.  Also, a stage could perform complicated Java logic to insert or process key parts of the XML, removing complexity from the XSLT stylesheet.  Finally, if requirements change later, stages could be added or removed without affecting existing transformation code.
        </p>
        <p>
        This diagram shows an example of a simple pipeline that takes an XML source and generates text, probably HTML (based off a diagram from <a href="http://cocoon.apache.org/2.1/userdocs/concepts/index.html">Cocoon</a>):
        </p>
        <img src="pipeline.gif" alt="Pipeline Diagram showing components" />
        <p>
        Finally, to wire components together, the pipeline framework uses the <a href="www.springframework.org">Spring Framework</a>, however only a couple of classes actually directly reference the Spring API and could be easily replaced to use another inversion of control framework or manual dependency management.
        </p>
    <a name="usage" />
    <h3>Usage</h3>
        <p>
        This framework is intended to be used as an embedded component by developers familiar with SAX-based XML processing, however where possible, convenience classes and methods provide an easier interface to common operations.  For most uses, an XML source transformed by the pipeline into a result, be it a DOM or OutputStream, so this usage information will cover such a case.
        </p>
        <h4>Define the Pipeline</h4>
        <p>Pipelines can be created either using the provided XMLPipelineFactory or by creating pipelines manually, however most cases will probably use the provided factory.  The <code>XMLPipelineFactory</code> uses simple definitions of pipelines using XML.  This example defines a pipeline named "foo" that performs a simple transformation into HTML:
        </p>
<pre><code>
&lt;pipelines&gt;
    &lt;pipeline name="foo"&gt;
        &lt;generator type="xml" /&gt;
        &lt;transformer type="trax" xslPath="foo.xsl" /&gt;
        &lt;serializer type="text" outputType="html" /&gt;
    &lt;/pipeline&gt;
&lt;pipelines&gt;    
</code></pre>
        <h4>Initialize the Pipelines</h4>
        <p> 
        This Java code initializes the pipeline:
        </p>
<pre><code>
InputStream springConfig = new FileInputStream("springPipelineConfig.xml");
InputStream pipeConfig = new FileInputStream("pipelines.xml");
XMLPipelineFactory factory = new XMLPipelineFactory(springConfig, pipeConfig);
</code></pre>
        <h4>Create the Context</h4>
        <p>
        The pipeline framework uses a shared <code>PipelineContext</code> to pass execution parameters to pipeline components.  The context will primarily be used to store the <code>Source</code> and <code>Result</code>, but could also be used to share objects like <code>Locale</code> or a message resources facade to a custom component.  This code creates a context and initializes it to use a file as a  <code>Source</code> and write the result to the console.
        </p>
<pre><code>
Source source = new StreamSource("foo.xml");
Result result = new StreamResult(System.out);
PipelineContext ctx = new PipelineContext(source, result);
</code></pre>
        <h4>Run the pipeline</h4>
        <p>
        Finally, retrieve the pipeline using the aforementioned pipeline factory and execute it with the <code>PipelineContext</code>:
        </p>
<pre><code>
Pipeline pipeline = factory.getPipeline("foo");
pipeline.execute(ctx);
</code></pre>
        <a name="status" />
     <h3>Status</h3>
        <p>
        This code is based on code used to perform complex DOM-to-DOM transformations and in another project, forms the basis of a portal's URL rewriting and XSL transformation engine.  I plan to look into how to backport the code to use this library which might result in minor changes to this framework.  Another area of interest is to use this pipeline as the basis for <a href="http://stxx.sf.net">stxx</a>, an XML processing extension to <a href="http://struts.apache.org">Struts</a>.
        <p>
            <b>0.3</b>
            <ul>
                <li>Added support for InputStream input</li>
            </ul>    
            <b>0.2</b>
            <ul>
                <li>Added missing config files in release</li>
		<li>Fixed bug where when one transformer, it would be skipped</li>
            </ul>    
            <b>0.1</b>
            <ul>
                <li>Initial release</li>
            </ul>    
        </p>
       </body>
       </html>
